home *** CD-ROM | disk | FTP | other *** search
/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / lang_c / mschrt / mschrtv2.doc < prev   
Text File  |  1989-02-04  |  18KB  |  678 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.                                   MSCHRT V2.00
  24.  
  25.                      Microsoft C High Resolution Timer Toolbox
  26.  
  27.  
  28.  
  29.  
  30.                                   Ryle Design
  31.  
  32.                    P.O. Box 22, Mt. Pleasant, Michigan  48804
  33.  
  34.                              CompuServe 73047,1765
  35.  
  36.  
  37.  
  38.  
  39.  
  40.                                  What is MSCHRT? 
  41.  
  42. MSCHRT (Microsoft C High Resolution Timer) is a software "toolbox" of routines 
  43. to manipulate one hundred different timers each with one microsecond resolu-
  44. tion.  MSCHRT makes it easy to very accurately time nearly any synchronous or
  45. asynchronous event your PC can encounter.  Since the timer routines calibrate
  46. themselves to the host PC speed at run-time a single executable file will 
  47. yield accurate timings across all 80xxx PC compatible environments.  A 
  48. complete report of all timer activity can be generated with a single MSCHRT 
  49. function call.
  50.  
  51. Some uses for MSCHRT are:
  52.  
  53.     Source Code Timer/Profiler
  54.     --------------------------
  55.     By adding calls to MSCHRT in source code under development, the execution 
  56.     of that code can generate a detailed summary of execution time by program
  57.     subroutine and immediately show the developer the program's "hot spots"
  58.     that might benefit from further code or algorithm optimization.   Unlike
  59.     "binning" profilers that display the number of "hits" in a range of program
  60.     counter addresses, MSCHRT provides a direct one to one correspondence
  61.     between source code and elapsed time with user defined granularity.  A
  62.     single line of source code can easily be timed with the insertion of two
  63.     MSCHRT procedure calls.
  64.  
  65.     Hardware Performance Evaluator
  66.     ------------------------------
  67.     The high resolution and self calibration features of MSCHRT make it ideal
  68.     for insertion in code to evaluate hardware performance.  Disk drives,
  69.     numeric processors and video controllers can all have their throughput
  70.     measured very accurately with MSCHRT, and with one hundred timers at the
  71.     user's disposal, many device functions can be independently measured in a
  72.     single run.  The formatted timer report generated by MSCHRT makes
  73.     compilation and interpretation of the test results quick and simple.
  74.  
  75.     Process Control Applications
  76.     ----------------------------
  77.     With MSCHRT, process control and data acquisition applications that require
  78.     precise timing are easy to implement.  No longer will the application
  79.     developer have to make an educated guess as to how long a critical hardware
  80.     interrupt is taking to service - MSCHRT timer calls can be inserted in the
  81.     interrupt handler and precise, accurate timing of the critical procedure is
  82.     assured.
  83.  
  84.     Timing and Scoring Equipment
  85.     ----------------------------
  86.     MSCHRT is the perfect "timer engine" to build a timing and scoring system
  87.     for nearly any competitive event that requires high resolution timing.  
  88.     With it's one microsecond (0.000001) resolution, MSCHRT surpasses
  89.     conventional sports timing equipment resolution and thus allows the
  90.     application developer to package both high resolution timing and complete 
  91.     event scoring in a single package.
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.                                       -1-
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.                                Distribution List 
  106.  
  107. The distribution you have received should contain the following:
  108.  
  109.     MSCHRTV2.DOC    This document
  110.     MSCHRT.H        C header file
  111.     MSCHRTS.LIB     Microsoft C small model link library
  112.     MSCHRTL.LIB     Microsoft C large model link library
  113.     DEMOV2.C        Simple demonstration of MSCHRT functions
  114.  
  115.  
  116.                            Version 2.00 Enhancements 
  117.  
  118. Version 2.00 of MSCHRT brings six new functions to the timer toolbox.  Briefly
  119. they are as follows:
  120.  
  121.     t_reset     Allows resetting of one or all active timers
  122.     t_ask_timer Queries a specified timer and returns activation and elapsed
  123.                 time counts
  124.     t_fname     Allows the user to specify a file name for the timer report
  125.     t_rname     Allows the user to specify a title for the timer report
  126.     t_suspend   Suspends an active timer temporarily
  127.     t_resume    Causes a previously suspended timer to resume activity
  128.  
  129. In addition, the version 1.00 function t_calib has been integrated into the
  130. t_start function and no longer needs to be explicitly called after t_start.  In
  131. the interest of backward compatibility the t_calib function has been retained
  132. in the MSCHRT libraries, but users should remove the t_calib calls as they 
  133. update their code to use the new functions in version 2.00.
  134.  
  135. Complete information on all MSCHRT functions is available in the reference
  136. chapter of this document.
  137.             
  138.  
  139.                      Additional Functions With Registration 
  140.  
  141. This copy of MSCHRT is a shareware evaluation copy which you are encouraged to
  142. experiment with without obligation.  If you find this timer toolbox to be useful
  143. you are encouraged to register your evaluation copy with Ryle Design, who will
  144. in turn provide you with the following:
  145.     
  146.     1.  Documentation of the low level MSCHRT timer functions
  147.  
  148.     2.  Functions to profile selected BIOS interrupts 
  149.  
  150.             t_bios_start        enables BIOS interrupt profiling
  151.             t_bios_stop         disables BIOS interrupt profiling
  152.             t_bios_suspend      suspends BIOS interrupt profiling
  153.             t_bios_resume       resumes BIOS interrupt profiling
  154.             t_bios_reset        resets BIOS timers
  155.             t_bios_ask          returns time & count for BIOS interrupt  
  156.             t_bios_report       generates BIOS timer summary
  157.             t_bios_fname        specifies file name for BIOS timer summary
  158.             t_bios_rname        specifies title for BIOS timer summary
  159.                 
  160.  
  161.  
  162.                                       -2-
  163.  
  164.  
  165.  
  166.  
  167.  
  168.     3.  Assembly language enhancements for users inserting MSCHRT timers
  169.         in interrupt handlers.
  170.  
  171.     4.  Example code:
  172.  
  173.             SEEKTEST.C  - tests disk seek time
  174.             WATCH.C     - dual stopwatch driven by keyboard interrupt 9h
  175.             HITIME.C    - TSR high resolution timer    
  176.  
  177.     5.  Complete, carefully commented source code to the entire MSCHRT library
  178.         including the t_bios extensions.
  179.  
  180.     6.  Technical support via CompuServ Easyplex mail.
  181.  
  182.  
  183. Registration is $7.50 which includes return shipping by first class mail in a
  184. crush proof disk envelope.  Ryle Design also has versions of the timer toolbox
  185. available for Turbo Pascal V5.00 (TPHRT) and Microsoft C V5.1 (MSCHRT).  These
  186. are also available for $7.50 each from Ryle Design.  Note that the code for
  187. Microsoft C and Microsoft C is different as Microsoft C does not support inline 
  188. asm statements as Borland does.
  189.  
  190. A registration form is provided for your convenience as the last page of this
  191. document.
  192.  
  193.  
  194.                              V2.00 Quick Reference
  195.  
  196. Users already familiar with Ryle Design PC Timer Toolboxes can reference the 
  197. following function list to begin using MSCHRT immediately.
  198.  
  199.     void t_ask_timer(int timer, long unsigned *count, long unsigned *elapsed)
  200.     void t_entry(int timer)
  201.     void t_exit(int timer)
  202.     void t_fname(char *file_name);
  203.     void t_name(int timer, char *timer_name)
  204.     void t_report(int where_to)
  205.     void t_reset(int timer)
  206.     void t_resume(int timer)
  207.     void t_rname(char *report_title)
  208.     void t_start(void)
  209.     void t_stop(void)
  210.     void t_suspend(int timer)
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.                                       -3-
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.                             MSCHRT Function Reference
  234.  
  235.  
  236. t_ask_timer
  237.  
  238.     
  239. Prototype       void t_ask_timer(int timer, long unsigned *count, 
  240.                                  long unsigned *elapsed)
  241.  
  242. Purpose         To get current activation counts and accumulated elapsed time
  243.                 for a specific timer.
  244.  
  245. Usage           t_start(2,&hits,&elapsed);
  246.         
  247. Side Effects    None.  Queries MSCHRT data structure, makes no DOS or BIOS
  248.                 calls.
  249.  
  250. Explanation     This function and t_report are the means by which the user
  251.                 gets timer results.  This function returns the number of
  252.                 timer activations and the amount of elapsed time (in micro-
  253.                 seconds) those activations consumed for a specific timer. 
  254.                 This function is useful when the user wishes information on 
  255.                 a specific timer or wishes to format his/her own timer report.
  256.  
  257. See also        t_report
  258.  
  259.  
  260. ________________________________________________________________________________
  261.  
  262.  
  263.  
  264. t_entry
  265.  
  266.  
  267. Prototype       void t_entry(int timer)
  268.  
  269. Purpose         Starts a specific timer.
  270.  
  271. Usage           t_entry(2);
  272.  
  273. Side Effects    Interrupts are ON when t_entry() returns.  Makes no DOS or
  274.                 BIOS calls.
  275.  
  276. Explanation     This function causes the specified timer to begin counting
  277.                 and to increment its activation count.  The counter stops
  278.                 counting and adds to its total elapsed time with a call to
  279.                 t_exit.
  280.  
  281.                 Timers should be used in ascending order starting at 0.
  282.                 Highest timer available is 99.
  283.  
  284. See also        t_exit
  285.  
  286.  
  287.  
  288.  
  289.  
  290.                                       -4-
  291.  
  292.  
  293.  
  294.  
  295. t_exit
  296.  
  297.  
  298. Prototype       void t_exit(int timer)
  299.  
  300. Purpose         Stops a specific timer.
  301.  
  302. Usage           t_exit(2);
  303.  
  304. Side Effects    Interrupts are ON when t_exit() returns.  Makes no DOS or
  305.                 BIOS calls. 
  306.  
  307. Explanation     This function causes the specified timer to stop counting
  308.                 and to add the elapsed time for this activation to the total
  309.                 elapsed time for this timer.  Each t_entry call must have 
  310.                 a corresponding t_exit call.
  311.  
  312. See also        t_entry
  313.  
  314.  
  315. ________________________________________________________________________________
  316.  
  317.  
  318.  
  319. t_fname
  320.  
  321.  
  322. Prototype       void t_fname(char *filename)
  323.  
  324. Purpose         Changes the default report summary file name from PROFILE.TXT
  325.                 to a user specified name.
  326.  
  327. Usage           t_fname("NEWNAME.TXT");
  328.  
  329. Side Effects    None.  Modifies MSCHRT data structure, makes no DOS or BIOS
  330.                 calls.
  331.  
  332. Explanation     t_report can send a timer report to a disk file, which uses
  333.                 PROFILE.TXT as a default name.  This function allows the
  334.                 user to specify some other file name using the full DOS
  335.                 drive:\path\name specification.  Maximum string length is
  336.                 66 characters.
  337.  
  338. See also        t_report
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.                                       -5-
  355.  
  356.  
  357.  
  358.  
  359. t_name      
  360.  
  361.  
  362. Prototype       void t_name(int timer, char *timer_name)
  363.  
  364. Purpose         Attaches a descriptive string to a specified timer.
  365.  
  366. Usage           t_name(2,"2D FFT");
  367.  
  368. Side Effects    None.  Modifies MSCHRT data structure, makes no DOS or BIOS
  369.                 calls.
  370.  
  371. Explanation     t_name allows the user to associate a descriptive string
  372.                 with each timer.  This string will appear next to the timer
  373.                 number on the timer report generated by t_report.  Maximum
  374.                 string length is 20 characters.
  375.  
  376. See also        t_report
  377.  
  378.  
  379. ________________________________________________________________________________
  380.  
  381.  
  382.  
  383. t_report        
  384.  
  385.  
  386. Prototype       void t_report(int whereto)
  387.  
  388. Purpose         Generates a summary of all timer activity
  389.  
  390. Usage           t_report(0);
  391.  
  392. Side Effects    Calls DOS to do output.  Not suitable for use in an interrupt
  393.                 handler.
  394.  
  395. Explanation     This function displays the following information on all
  396.                 active timers:
  397.                     Timer description (from t_name)
  398.                     Number of activations
  399.                     Total activation time
  400.                     Average activation time
  401.  
  402.                 A count is kept of the highest timer activated, and all
  403.                 timers up to that number are displayed, so timers should
  404.                 be used in ascending order starting at 0.
  405.  
  406.                 The timer report has a title, which defaults to 
  407.                 "Profile Summary".  This can be changed with t_rname.
  408.  
  409.                 The integer flag whereto specifies the report destination:
  410.                     0 = CRT
  411.                     1 = file PROFILE.TXT or change with t_fname
  412.                     2 = printer (PRN)
  413.                                 
  414. See also        t_name, t_rname, t_fname                    
  415.  
  416.  
  417.  
  418.                                       -6-
  419.  
  420.  
  421.  
  422.  
  423. t_reset
  424.  
  425.  
  426. Prototype       void t_reset(int timer)
  427.  
  428. Purpose         Allows the user to reset one or all timers
  429.  
  430. Usage           t_reset(2);
  431.  
  432. Side Effects    None.  Modifies MSCHRT data structure, makes no DOS or BIOS
  433.                 calls.
  434.  
  435. Explanation     This function zeros both activation count and elapsed time
  436.                 for a specified timer (0-99).  By passing -1 as the timer
  437.                 number, all timers will be reset.
  438.  
  439. See also        No other related functions.
  440.  
  441.  
  442.  
  443. ________________________________________________________________________________
  444.  
  445.  
  446.  
  447. t_resume
  448.  
  449.  
  450. Prototype       void t_resume(int timer)
  451.  
  452. Purpose         Restarts a previously suspended timer
  453.  
  454. Usage           t_resume(2);
  455.  
  456. Side effects    Interrupts are ON when t_resume returns.  Makes no DOS or
  457.                 BIOS calls.
  458.  
  459. Explanation     This functions restarts a timer temporarily stopped with
  460.                 t_suspend.
  461.  
  462. See also        t_suspend
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.                                       -7-
  483.  
  484.  
  485.  
  486.  
  487. t_rname
  488.  
  489.  
  490. Prototype       void t_rname(char *report_title)
  491.  
  492. Purpose         Changes default timer report title from "Profile Summary"
  493.                 to a user specified string.
  494.  
  495. Usage           t_rname("Timings with 20 Mhz 80387");
  496.  
  497. Side effects    None.  Modifies MSCHRT data structure, makes no DOS or BIOS
  498.                 calls.
  499.  
  500. Explanation     t_report generates a timer summary with the default title
  501.                 "Profile Summary".  This function allows the user to specify
  502.                 a different, more descriptive string.  Maximum string length
  503.                 is 80 characters.  The string is centered on the line.
  504.  
  505. See also        t_report
  506.  
  507.  
  508. ________________________________________________________________________________
  509.  
  510.  
  511.  
  512. t_start
  513.  
  514.  
  515. Prototype       void t_start(void)
  516.  
  517. Purpose         Initializes MSCHRT timing primitives.  
  518.  
  519. Usage           t_start();
  520.  
  521. Side effects    Changes 8253 timer to mode 2.  Makes no DOS or BIOS calls.
  522.  
  523. Explanation     This function initializes and calibrates the MSCHRT timing 
  524.                 primitives, and must be called before any other MSCHRT
  525.                 functions are invoked.
  526.  
  527. See also        t_stop
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.                                       -8-
  547.  
  548.  
  549.  
  550.  
  551. t_stop
  552.  
  553.  
  554. Prototype       void t_stop(void)
  555.  
  556. Purpose         Disables all MSCHRT timing primitives.
  557.  
  558. Usage           t_stop();
  559.  
  560. Side effects    Changes 8253 timer back to mode 3.  Makes no DOS or BIOS calls.
  561.                 
  562. Explanation     This function should be called when all active timers have
  563.                 been stopped prior to program termination.
  564.  
  565. See also        t_start
  566.  
  567.  
  568. ________________________________________________________________________________
  569.  
  570.  
  571.  
  572. t_suspend
  573.  
  574.  
  575. Prototype       void t_suspend(int timer)
  576.  
  577. Purpose         Temporarily stops an active timer.
  578.  
  579. Usage           t_suspend(2)
  580.  
  581. Side effects    Interrupts are ON when t_suspend returns.  Makes no DOS or
  582.                 BIOS calls.
  583.  
  584. Explanation     This function allows a timer to be stopped and restarted 
  585.                 without an additional activation count being added.  Useful
  586.                 if you use activation counts to track the number of function
  587.                 calls but for some reason want to stop the timer and restart
  588.                 it again later in the same function.
  589.  
  590. See also        t_resume.                
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.                                       -9-
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.                             MSCHRT Registration Form
  620.  
  621.  
  622.  
  623.     Name __________________________________________________________________
  624.  
  625.     Address _______________________________________________________________
  626.  
  627.     City/State/Zip ________________________________________________________
  628.  
  629.     Daytime Telephone _____________________________________________________
  630.  
  631.     CompuServ ID (for tech support) _______________________________________
  632.  
  633.     Where did you get your copy of MSCHRT?  ________________________________
  634.  
  635.     What is your primary use of MSCHRT? ____________________________________
  636.  
  637.     Comments regarding this product _______________________________________
  638.  
  639.     _______________________________________________________________________
  640.  
  641.     _______________________________________________________________________
  642.  
  643.     _______________________________________________________________________
  644.  
  645.  
  646.     Check Products desired:
  647.  
  648.  
  649.     ____    MSCHRT Registered Version (Microsoft C V5.1/MSDOS) ......  7.50
  650.  
  651.  
  652.     ____    TPHRT Registered Version (Turbo Pascal V5.0) ............  7.50
  653.  
  654.  
  655.     ____    TCHRT Registered Version (Turbo C V2.0) .................  7.50
  656.  
  657.     
  658.     ____    All three of the above (save 2.50) ...................... 20.00
  659.  
  660.  
  661.             Subtotal ................................................ _____
  662.  
  663.             
  664.             Michigan residents add 4% sales tax ..................... _____
  665.  
  666.  
  667.             Total enclosed (__check __money order) .................. _____
  668.  
  669.  
  670.     Remit to:   Ryle Design
  671.                 P.O. Box 22
  672.                 Mt. Pleasant, Michigan 48804
  673.  
  674.  
  675.  
  676.  
  677.  
  678.